Mimas 0.2
=========

 Mimas is an integrated development enviroment for writing Z80
 assembly programs on the Texas Instruments TI-83 Plus, TI-84 Plus,
 and TI-Nspire graphing calculators.  Using Mimas, you can write,
 compile, and run programs in assembly language, entirely on the
 calculator; no PC or other tools are required.


Installing Mimas
----------------

 Mimas is a Flash application.  You will need to have a link cable and
 appropriate software on your PC in order to install Mimas on your
 calculator.  (See http://www.ticalc.org/basics/linking/ for more
 information about link cables.)

 Mimas itself (mimas.8xk) requires two app slots (32768 bytes) of
 archive memory.  In addition, you may want to install some or all of
 the provided "header" files (see below).


Using Mimas
-----------

 When you are writing an assembly program, it is stored on the
 calculator as an application variable (AppVar.)  This is similar to
 an assembly source file (.asm or .z80) that you would write on a PC;
 when you want to run your program, you will first need to compile it
 (which produces a normal program file that you can run using 'Asm('
 or your favorite shell.)

 Programs can be divided into sections, which are marked either as
 "code" or "data".  The significance is that all code sections are
 assembled before all data sections (which is important for large
 programs.)  By default, a single code section is created for you,
 called MAIN.

 A program may include a list of "libraries" - additional program
 files that will be combined with the main program when it is
 compiled.  Only one copy of each library will be included, even if it
 is listed in multiple places.

 Program source files must be stored in RAM to be edited; if a file is
 archived and you try to modify it, it will be unarchived
 automatically.  It is generally wise to keep your files archived when
 you're not working on them (and for large programs, you may need to
 archive the source files before compiling.)

 For more information about using Mimas, see the User's Manual.


Library "Header" Files
----------------------

 The following extra "header files" are included with this package
 (see the 'libs' directory.)  These files define additional addresses
 and constants for you to use in your programs.  (In order to use the
 definitions provided by any of these files, you must import it into
 your program using the "Libraries" menu in Mimas.)

 The following header files define library routines for shell
 programs:

   ion.8xv       Library routines for (small) Ion programs
   mirage.8xv    Library routines for MirageOS programs
   dcs7.8xv      Library routines for DoorsCS7 programs

 The following header files define additional, less-commonly-used
 system routines (B_CALLs):

   display.8xv   Display-related routines
   math.8xv      Advanced math and FPS routines
   vars.8xv      Memory/variable management routines
   graph.8xv     Floating-point drawing and graphing routines
   hooks.8xv     Routines for setting and using system hooks
   edit.8xv      Routines for working with edit buffers
   gui.8xv       System GUI utility routines
   mon.8xv       Routines for controlling the system monitor
   flash.8xv     Routines for manipulating Flash memory
   boot.8xv      Cryptography and miscellaneous boot code routines
   boot84.8xv    Miscellaneous boot code routines for the TI-84+ only
   os110.8xv     New routines for OS 1.10
   os113.8xv     New routines for OS 1.13
   os115.8xv     New routines for OS 1.15
   os221.8xv     New routines for OS 2.21
   os230.8xv     New routines for OS 2.30
   os240.8xv     New routines for OS 2.40
   extra.8xv     Useless, duplicate, and non-callable routines


Converting Mimas Files to Standard Assembly Format
--------------------------------------------------

 To convert a Mimas file into a .asm file that you can edit on the PC,
 you can use the program '8xvtoasm'.  (A Windows version of this
 program is included in the 'tools' directory; for other systems, you
 can compile it by running 'make'.)

 This produces source code in the Mimas native format, similar to the
 way it's displayed on the calculator.  If you're using any
 Mimas-specific features (such as anonymous labels or the JQ
 instruction) in your program, you will probably need to modify the
 code somewhat in order to assemble it with your PC-based assembler of
 choice.

 (If you're not using any Mimas-specific features, you can probably
 assemble the code as-is.  But if you're using TASM or SPASM, note
 that you may need to add definitions such as "#define db .db" and
 "#define equ .equ".  Also, remember that TASM and SPASM don't handle
 binary operator precedence, so be careful!)


Converting Assembly Files to Mimas Format
-----------------------------------------

 To convert an existing .asm (or .inc) file into a Mimas file that you
 can edit on the calculator, you can use the program 'asmto8xv'.
 asmto8xv can understand most common source code formats, but for best
 results, you should specify the input format using the -f option.

 Note that this program doesn't support all the features of all the
 other assemblers - only the subset that can be readily translated
 into Mimas instructions.  In particular, Mimas doesn't support macros
 (yet), so asmto8xv doesn't support them either.  Source code lines
 that can't be understood will be included in the 8xv file as
 comments.